home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audio / ALgetstatus.z / ALgetstatus
Encoding:
Text File  |  1998-10-20  |  6.6 KB  |  133 lines
  1.  
  2.  
  3.  
  4. AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm))))                                              AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ALgetstatus - get information concerning the most recent error in the
  10.      audio stream associated with a port.
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  14.  
  15.      iiiinnnntttt AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((AAAALLLLppppoooorrrrtttt ppppoooorrrrtttt,,,, lllloooonnnngggg ****PPPPVVVVbbbbuuuuffffffffeeeerrrr,,,, lllloooonnnngggg bbbbuuuuffffffffeeeerrrrlllleeeennnnggggtttthhhh))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  18.      _p_o_r_t           expects the ALport to which this command applies.
  19.  
  20.      _P_V_b_u_f_f_e_r       expects an array of longs.  The even elements of this
  21.                     array should each contain an error variable that you
  22.                     choose to read. The subsequent odd elements are the
  23.                     current or new value of these variables.
  24.  
  25.      _b_u_f_f_e_r_l_e_n_g_t_h   expects the number of longs in the buffer pointed to by
  26.                     _P_V_b_u_f_f_e_r.  This value must be even.
  27.  
  28. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  29.      AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm)))) returns the current values for the port error variables
  30.      referenced in the _P_V_b_u_f_f_e_r array.  The values are written into the odd
  31.      locations of _P_V_b_u_f_f_e_r immediately after the corresponding error variable.
  32.  
  33.      Errors may occur in an audio stream if reading and writing samples does
  34.      not keep pace with the audio port. If an output port is not provided
  35.      enough samples, underflow occurs. Likewise, if data is not read from an
  36.      input port fast enough, an overflow error occurs. AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm)))) allows
  37.      for these errors to be detected and quantified. This information can
  38.      enable the program (or user) to change the behavior of the program to
  39.      eliminate errors.
  40.  
  41.      Two concepts regarding error detection deserve more explanation:
  42.  
  43.      I.  The length of the current error (AL_ERROR_LENGTH) is a sampled value,
  44.      and thus it may change even though the error count and/or the error
  45.      location may not. Note: if an error is particularly large, the length
  46.      variable may overflow its 24-bit limit.
  47.  
  48.      II. The location of the error marks the point in the port lifetime that
  49.      the error was detected. Thus, the location represents the number of
  50.      sample frames (sample pairs for stereo; single samples for mono) that
  51.      have passed through the port to the audio hardware. The error location is
  52.      a 48-bit number, allowing the port to be open and active for over 200
  53.      years without counter overflow. The 48-bit location is generated by
  54.      concatenating the lower 24 bits of the values associated with
  55.      AL_ERROR_LOCATION_LSP and AL_ERROR_LOCATION_MSP.
  56.  
  57.      The currently defined set of error parameters, found in _a_u_d_i_o._h, are:
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm))))                                              AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.           AL_ERROR_NUMBER
  75.                   The number of errors associated with the port since the port
  76.                   was opened. This count is initialized to 0 when the port is
  77.                   opened.
  78.           AL_ERROR_TYPE
  79.                   The type of error which has most recently occurred on the port.
  80.                   Supported error types are: AL_ERROR_INPUT_OVERFLOW and
  81.                   AL_ERROR_OUTPUT_UNDERFLOW.
  82.           AL_ERROR_LENGTH
  83.                   The current length (in samples frames) of the current error.
  84.                   Consecutive values of this variable may differ if the current
  85.                   error has not completed. Only the least significant 24 bits
  86.                   of this variable are valid.
  87.           AL_ERROR_LOCATION_LSP
  88.                   The least significant portion (LSP) of the location of the
  89.                   beginning of the current error (in samples frames). Only the 24
  90.                   least significant bits of this variable are valid.
  91.           AL_ERROR_LOCATION_MSP
  92.                   The most significant portion (MSP) of the location of the
  93.                   beginning of the current error (in samples frames). Only the 24
  94.                   least significant bits of this variable are valid.
  95.  
  96.           In order to maintain the greatest possible performance, AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm))))
  97.           does not verify the validity of _p_o_r_t, _P_V_b_u_f_f_e_r, or
  98.           _b_u_f_f_e_r_l_e_n_g_t_h. You should make certain that these are valid before
  99.           passing them as arguments to AAAALLLLggggeeeettttssssttttaaaattttuuuussss((((3333ddddmmmm)))).
  100.  
  101.  
  102. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  103.                #include <dmedia/audio.h>
  104.                ...
  105.                   ALport    port;
  106.                   ...
  107.                /* Get data concerning the most recent audio stream error */
  108.                long buf[10];
  109.                   buf[0] = AL_ERROR_NUMBER;
  110.                   buf[2] = AL_ERROR_TYPE;
  111.                   buf[4] = AL_ERROR_LENGTH;
  112.                   buf[6] = AL_ERROR_LOCATION_LSP;
  113.                   buf[8] = AL_ERROR_LOCATION_MSP;
  114.                ALgetstatus(port,buf,10);
  115.  
  116.  
  117. NNNNOOOOTTTTEEEE
  118.      Since an output port is initially empty, there may be an initial error
  119.      for the port.
  120.  
  121. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  122.      ALreadsamps(3dm), ALwritesamps(3dm)
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.